--- title: 1.2. Convenções da API url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/1.%20In%C3%ADcio/1.2.%20Conven%C3%A7%C3%B5es%20da%20API/ --- # 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](1.1.%20Primeiros%20Passos.md). --- ## 🔗 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](../9.%20Mudanças%20e%20Impacto%20nas%20Integrações.md). > 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](1.1.%20Primeiros%20Passos.md). | | `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. | ```bash 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" ``` !!! warning "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. | ```bash 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](../3.%20Notificações%20-%20WebHook/3.0.%20Visão%20Geral.md). --- ## 📄 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: ```json { "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: ```json { "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](../4.%20Agenda%20de%20recebíveis/v1.1/4.1.%20Solicitar%20agenda.md) | | Criação de contrato | **5.1. Criar contrato** | | Cancelamento de contrato | [5.9. Cancelar contrato](../5.%20Contrato%20de%20recebíveis/v1.1/5.9.%20Cancelar%20contrato.md) | | Remoção de UR do contrato | [5.8. Remover URs do contrato](../5.%20Contrato%20de%20recebíveis/v1.1/5.8.%20Remover%20URs%20do%20contrato.md) | 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. ```json { "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](../6.%20Liquidações/v1.1/6.1.%20Envio%20dos%20créditos%20em%20conta.md). --- ## 🔢 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](../3.%20Notificações%20-%20WebHook/3.0.%20Visão%20Geral.md). | | Consulta ativa | Alternativa de contingência, pelos endpoints de detalhes do recurso — por exemplo [4.3. Detalhes da agenda](../4.%20Agenda%20de%20recebíveis/v1.1/4.3.%20Detalhes%20da%20agenda.md) e [5.3. Detalhes do contrato](../5.%20Contrato%20de%20recebíveis/v1.1/5.3.%20Detalhes%20do%20contrato.md). | * **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 * Credenciais, autenticação e ambientes: [1.1. Primeiros Passos](1.1.%20Primeiros%20Passos.md). * Conceitos do produto (UR, agenda, carrinho, contrato): [2.1. Conceitos](../2.%20Introdução/2.1.%20Conceitos.md). * Notificações assíncronas: [3.0. Visão Geral](../3.%20Notificações%20-%20WebHook/3.0.%20Visão%20Geral.md). * Primeira chamada do fluxo: [4.1. Solicitar agenda](../4.%20Agenda%20de%20recebíveis/v1.1/4.1.%20Solicitar%20agenda.md). * Diferenças entre v1 e v1.1: [9. Mudanças e Impacto nas Integrações](../9.%20Mudanças%20e%20Impacto%20nas%20Integrações.md).