VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Cobrança e conciliação

Régua de cobrança: configuração

Liga ou desliga a régua de cobrança do seller e mantém as etapas (quando, por qual canal e com que mensagem cobrar).

Ler a régua

A régua de cobrança (dunning) é o roteiro de lembretes para clientes com conta a receber vencida: no dia X depois do vencimento, tal canal e tal mensagem. Esta rota lê se a régua do seller está ligada. Importante: a plataforma não envia nada sozinha. Ela monta a fila do que deveria ser cobrado e você registra o contato.

GET/api/v1/vendor/erp/cobranca/policySeller

Lê o estado da régua de cobrança

Exemplo de requisição: Ler a régua

bash
curl "$BASE_URL/api/v1/vendor/erp/cobranca/policy" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Ler a régua

200Estado da régua
json
{
  "status": "active"
}

Campos da resposta

statusstring
activeinactive
Estado da régua. Padrão inactive quando nunca foi configurada.

Erros: Ler a régua

StatusQuandoCorpo
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Ligar ou desligar a régua

PUT/api/v1/vendor/erp/cobranca/policySeller

Liga ou desliga a régua

Corpo da requisição

statusstringobrigatório
activeinactive
active ou inactive. Aceita maiúsculas.

Exemplo de requisição: Ligar ou desligar a régua

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/cobranca/policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

Resposta: Ligar ou desligar a régua

200Estado gravado
json
{
  "status": "active"
}

Campos da resposta

statusstring
activeinactive
Estado da régua. Padrão inactive quando nunca foi configurada.

Erros: Ligar ou desligar a régua

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400status fora dos dois valores.{"error":"vendorerp: status must be active|inactive"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
O estado não bloqueia a fila

A fila é montada mesmo com a régua inactive. O estado serve de sinal para a sua tela ou para o seu processo.

Listar etapas

Cada etapa diz o que fazer a partir de N dias do vencimento. A lista vem do menor para o maior offset_days, sem paginação.

GET/api/v1/vendor/erp/cobranca/stepsSeller

Lista as etapas da régua

Exemplo de requisição: Listar etapas

bash
curl "$BASE_URL/api/v1/vendor/erp/cobranca/steps" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar etapas

200Etapas
json
{
  "steps": [
    {
      "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "offset_days": 3,
      "channel": "whatsapp",
      "template_subject": "Boleto em atraso",
      "template_body": "Olá {cliente}, o valor de {valor} venceu em {vencimento} ({dias_atraso} dias). Podemos ajudar?",
      "position": 1,
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

stepsarray

Etapas.

iduuid
Id da etapa.
vendor_iduuid
Seller dono.
offset_daysinteger
Dias em relação ao vencimento em que a etapa vale (3 = três dias depois de vencer).
channelstring
emailwhatsappphonemanual
Canal sugerido.
template_subjectstring
Assunto do modelo (para e-mail).
template_bodystring
Texto do modelo, com marcadores.
positioninteger
Posição livre para ordenar na tela.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
totalinteger
Quantidade devolvida.

Erros: Listar etapas

StatusQuandoCorpo
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Criar ou atualizar etapa

Grava uma etapa. O par (seller, offset_days) é único: enviar de novo o mesmo offset_days atualiza a etapa existente (e restaura uma apagada) em vez de criar outra. Por isso a resposta é sempre 200, também na criação.

POST/api/v1/vendor/erp/cobranca/stepsSeller

Cria ou atualiza uma etapa

Corpo da requisição

offset_daysintegerobrigatório
De -30 a 180. Negativo é antes do vencimento, mas a fila só cobre títulos já vencidos.
channelstringpadrão: email
emailwhatsappphonemanual
Canal. Padrão email.
template_subjectstring
Assunto, para e-mail.
template_bodystringobrigatório
Texto do modelo. Obrigatório. Aceita os marcadores {cliente}, {valor} (formatado em reais), {vencimento} e {dias_atraso}.
positioninteger
Posição livre. Padrão 0.

Exemplo de requisição: Criar ou atualizar etapa

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/cobranca/steps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "offset_days": 3,
  "channel": "whatsapp",
  "template_subject": "Boleto em atraso",
  "template_body": "Olá {cliente}, o valor de {valor} venceu em {vencimento} ({dias_atraso} dias). Podemos ajudar?",
  "position": 1
}'

Resposta: Criar ou atualizar etapa

200Etapa gravada
json
{
  "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "offset_days": 3,
  "channel": "whatsapp",
  "template_subject": "Boleto em atraso",
  "template_body": "Olá {cliente}, o valor de {valor} venceu em {vencimento} ({dias_atraso} dias). Podemos ajudar?",
  "position": 1,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id da etapa.
vendor_iduuid
Seller dono.
offset_daysinteger
Dias em relação ao vencimento em que a etapa vale (3 = três dias depois de vencer).
channelstring
emailwhatsappphonemanual
Canal sugerido.
template_subjectstring
Assunto do modelo (para e-mail).
template_bodystring
Texto do modelo, com marcadores.
positioninteger
Posição livre para ordenar na tela.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Criar ou atualizar etapa

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400offset_days fora da faixa.{"error":"vendorerp: offset_days must be between -30 and 180"}
400Canal inválido.{"error":"vendorerp: channel must be email|whatsapp|phone|manual"}
400template_body em branco.{"error":"vendorerp: template_body required"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Apagar etapa

DELETE/api/v1/vendor/erp/cobranca/steps/{id}Seller

Apaga uma etapa

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da etapa.

Exemplo de requisição: Apagar etapa

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/erp/cobranca/steps/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Apagar etapa

200Etapa apagada
json
{
  "message": "step deleted"
}

Campos da resposta

messagestring
Sempre step deleted.

Erros: Apagar etapa

StatusQuandoCorpo
404A etapa não existe ou já foi apagada.{"error":"dunning step not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Veja também

  • Fila e contatos
  • Contas a receber
Anterior
ERP de cobrança e conciliação
Próxima
Régua de cobrança: fila e contatos
Nesta página
  • Ler a régua
  • Exemplo de requisição: Ler a régua
  • Resposta: Ler a régua
  • Erros: Ler a régua
  • Ligar ou desligar a régua
  • Exemplo de requisição: Ligar ou desligar a régua
  • Resposta: Ligar ou desligar a régua
  • Erros: Ligar ou desligar a régua
  • Listar etapas
  • Exemplo de requisição: Listar etapas
  • Resposta: Listar etapas
  • Erros: Listar etapas
  • Criar ou atualizar etapa
  • Exemplo de requisição: Criar ou atualizar etapa
  • Resposta: Criar ou atualizar etapa
  • Erros: Criar ou atualizar etapa
  • Apagar etapa
  • Exemplo de requisição: Apagar etapa
  • Resposta: Apagar etapa
  • Erros: Apagar etapa
  • Veja também