Ir para o conteúdo

1.2. Convenções da API

🧾 Descrição

Esta página reúne as convenções transversais da API de cartão da plataforma VeFlow: base das rotas, headers obrigatórios, idempotência, paginação, códigos de resposta, formato de erro, janela de operação, formatos de dado e acompanhamento do processamento assíncrono.

Tudo o que está aqui vale para todos os endpoints das seções 4 a 7, e por isso as páginas de endpoint apenas referenciam esta. A obtenção das credenciais, o fluxo de autenticação e a diferença entre os ambientes estão em 1.1. Primeiros Passos.

🔗 Base e Versionamento

Todas as chamadas da API de cartão partem desta base:

https://api.veflow.com/public/api/v1.1/cartao
Versão Situação Base
v1 Versão atual /public/api/v1/cartao
v1.1 Versão em testes assistidos /public/api/v1.1/cartao

Regras de convivência entre as versões:

  • As duas versões convivem no mesmo host. A publicação da v1.1 não desligou a v1.
  • Nada da v1 foi alterado: rotas, nomes de campo e comportamento seguem exatamente como estavam. Quem já integra a v1 não precisa mudar nada para continuar operando.
  • A v1.1 é a versão em evolução e concentra o fluxo completo de agenda, carrinho, contrato, liquidações e conciliação. Toda nova integração deve nascer nela.
  • O que muda de uma versão para a outra, e o impacto de migrar, está em 9. Mudanças e Impacto nas Integrações.

Nas páginas de endpoint, a coluna URL da tabela mostra a rota relativa (por exemplo /public/api/v1.1/cartao/agendas). Nos exemplos de cURL a URL aparece completa, com o host https://api.veflow.com.

📨 Headers Obrigatórios

Header Tipo Obrigatório Descrição
Authorization Bearer Token Sim Bearer Token obtido via Keycloak — ver 1.1. Primeiros Passos.
GrupoEconomico string Sim Identificador do grupo econômico, entregue na liberação do acesso. Obrigatório em toda requisição.
Content-Type string Sim nas requisições com corpo Sempre application/json. O corpo é JSON em UTF-8.
Idempotency-Key string Recomendado nas escritas GUID da operação lógica. Ver a seção Idempotência abaixo. 
curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas?indicePagina=1&tamanhoDaPagina=20" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

O header GrupoEconomico é obrigatório em todas as requisições

Ele acompanha o token em qualquer chamada, inclusive nas consultas (GET). É esse header que define em nome de qual grupo econômico a requisição é executada, e ele determina quais agendas, carrinhos e contratos ficam visíveis. Requisições sem ele são recusadas com 401.

🪞 Idempotência

Os endpoints de escrita (POST) aceitam o header Idempotency-Key, que protege a operação contra duplicidade em caso de retentativa.

Regra Comportamento
Valor da chave Envie um UUID por operação lógica — uma solicitação de agenda, um contrato, um item de carrinho.
Reenvio da mesma chave A plataforma devolve a resposta original da primeira chamada, em vez de duplicar a operação.
Chave nova É interpretada como uma nova operação e executa normalmente.
Retentativa automática Recomendado sempre: timeout, erro de rede ou 5xx deixam a operação em estado desconhecido para o cliente, e repetir a chamada com a mesma chave é o que garante que ela não aconteça duas vezes. 
curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0" \
  -H "Content-Type: application/json" \
  -d '{ "...": "..." }'
  • Gere o UUID antes da primeira tentativa e guarde-o junto do registro da operação no seu sistema. Uma chave gerada a cada tentativa não protege contra nada.
  • Não reaproveite a mesma chave para operações diferentes.
  • O mesmo cuidado vale no sentido inverso: as notificações enviadas pela plataforma também carregam Idempotency-Key, e o endpoint de callback do cliente precisa deduplicar por ela — ver 3.0. Visão Geral.

📄 Paginação

Todos os endpoints de listagem são paginados e aceitam os mesmos query params:

Parâmetro Tipo Obrigatório Descrição
indicePagina integer Não Página desejada. Default 1.
tamanhoDaPagina integer Não Quantidade de registros por página. Default 20.
ordem string Não Campo de ordenação. Os campos aceitos estão na página de cada listagem.
direcaoOrdem string Não Direção da ordenação: ASC ou DESC.

📦 Envelope de Lista

A resposta de qualquer listagem tem sempre esta forma:

{
  "registros": [],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 3,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 47,
    "temPaginaAnterior": false,
    "temProximaPagina": true
  },
  "mensagem": null
}
Campo Tipo Descrição
registros array Registros da página atual. O conteúdo de cada item é descrito na página do endpoint.
paginacao object Bloco de paginação, detalhado abaixo.
mensagem string/null Mensagem informativa opcional. Em caso de sucesso normalmente vem null.

🔹 paginacao

Campo Tipo Descrição
paginaAtual integer Página atual do retorno.
paginaTotal integer Total de páginas disponíveis.
paginaQuantidadeRegistro integer Quantidade máxima de registros por página.
quantidadeRegistros integer Total de registros encontrados.
temPaginaAnterior boolean Indica se há página anterior.
temProximaPagina boolean Indica se há próxima página.
  • Percorra as páginas até temProximaPagina vir false. Esse é o critério de parada, e não uma contagem calculada no cliente.
  • Uma listagem sem resultados devolve 200 com registros vazio — não é 404.
  • Os filtros de cada listagem são combinados com E (todos precisam ser satisfeitos) e valem junto com a paginação.

✅ Códigos de Resposta

Código Significado
200 OK Consulta atendida ou comando síncrono concluído.
201 Created Recurso criado de forma síncrona. O header Location da resposta aponta o recurso criado.
202 Accepted Requisição recebida para processamento assíncrono. A resposta devolve identificadorProcessamento para acompanhamento — e, fora da janela de operação, também dataAgendamento.
400 Bad Request Falha de validação: campo obrigatório ausente, tipo incorreto ou formato inválido.
401 Unauthorized Falha de autenticação: token ausente, inválido ou expirado — ou header GrupoEconomico ausente.
403 Forbidden Requisição autenticada, mas sem permissão para o recurso ou para o grupo econômico informado.
404 Not Found Recurso inexistente para o grupo econômico informado (agenda, UR, item de carrinho ou contrato).
409 Conflict Conflito de estado: o recurso não admite a operação na posição em que está (por exemplo, cancelar um contrato já cancelado).
422 Unprocessable Entity Regra de negócio violada: a requisição é válida em forma, mas não pode ser executada (por exemplo, agenda vencida, ou valor pedido acima do valorDisponivel das URs).

Um comando assíncrono nunca responde 201. Criação agendada ou enfileirada responde 202 Accepted.

❌ Formato de Erro

Todo erro da API usa um único formato, no padrão RFC 9110, independentemente do status:

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'cnpj' é obrigatório.",
    "Campo 'dataInicial' inválido. Formato esperado: YYYY-MM-DD."
  ]
}
Campo Tipo Descrição
tipo string URI da seção da RFC 9110 correspondente ao status devolvido.
titulo string Título curto do erro.
status integer Código HTTP, igual ao status da resposta.
erros string[] Lista de mensagens: uma mensagem por problema encontrado.

O array erros é sempre uma lista, mesmo quando há um único problema. A plataforma valida a requisição inteira antes de responder, então uma única chamada pode devolver vários itens de uma vez. Trate-o como coleção: registre e exiba todas as mensagens, em vez de ler apenas a primeira posição.

🕒 Janela de Operação

As operações que dependem de comunicação com as registradoras são processadas apenas entre 09:00 e 18:00 em dias úteis:

Operação Página
Solicitação de agenda 4.1. Solicitar agenda
Criação de contrato 5.1. Criar contrato
Cancelamento de contrato 5.9. Cancelar contrato
Remoção de UR do contrato 5.8. Remover URs do contrato

Fora da janela, a requisição não é recusada: a resposta é 202 Accepted com o campo dataAgendamento, informando o próximo dia útil em que o processamento vai ocorrer.

{
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "dataAgendamento": "2025-08-11",
  "mensagem": "Solicitação recebida e agendada para processamento no próximo dia útil."
}

O envio de liquidações não tem limite de horário e pode ser enviado a qualquer momento. Ainda assim, envie após as 10h05: o processamento em lote das agendas roda às 10h00, e o envio feito antes disso concorre com esse lote — ver 6.1. Envio dos créditos em conta.

🔢 Formatos

Item Formato Exemplo
Nomes de campo camelCase dataPrevistaLiquidacao
Data YYYY-MM-DD 2025-08-09
Data e hora ISO 8601 2025-08-09T14:32:10Z
CNPJ Somente dígitos na entrada, sem pontuação 12345678000199
Valor decimal Ponto como separador decimal, sem separador de milhar 1500.75
Valor monetário number com 2 casas decimais 1500.75
Taxa number com até 4 casas decimais 1.9900
  • CNPJ enviado com máscara (12.345.678/0001-99) é recusado com 400. Nas respostas o CNPJ também vem sem formatação.
  • Valores decimais são enviados e recebidos como number JSON, nunca como string com vírgula.
  • A taxa só se aplica a contratos de troca de titularidade. Contratos de garantia não têm deságio e por isso não recebem nem devolvem taxa.

⏳ Processamento Assíncrono

Operações que dependem das registradoras — consulta de agenda, registro e cancelamento de contrato, remoção de UR — são assíncronas. A resposta 202 Accepted confirma apenas o recebimento da requisição, não a conclusão do processamento.

Recurso Como acompanhar
identificadorProcessamento GUID devolvido no 202. Identifica o processamento e é a referência para acompanhamento e para acionar o suporte.
WebHook Forma recomendada. A plataforma notifica a conclusão na URL de callback do cliente — ver 3.0. Visão Geral.
Consulta ativa Alternativa de contingência, pelos endpoints de detalhes do recurso — por exemplo 4.3. Detalhes da agenda e 5.3. Detalhes do contrato.
  • Prefira WebHook a polling. O WebHook avisa no instante em que o processamento termina; o polling gasta chamada, atrasa a reação do seu sistema e não traz nenhuma informação adicional.
  • Use consulta ativa como contingência — quando a notificação não chegou após as retentativas, ou para reconciliar o estado depois de uma indisponibilidade do seu callback.
  • Não amarre o fluxo do usuário à resposta 202. Guarde o identificadorProcessamento e siga o fluxo quando a notificação chegar.

📎 Páginas Relacionadas