Neste guia
FullCash — Guia de Integração (Contas a Pagar e Arquivos)
Guia para desenvolvedores (e para IAs geradoras de código) entenderem como integrar um sistema externo ao Contas a Pagar do FullCash.
A API é o espelho do papel cliente: você pode ver o que um cliente vê e criar o que um cliente cria — nada além. O fluxo (validar, devolver, rejeitar) é do operador FullCash e não existe na API. O passo do cliente — reenviar para análise uma conta em Pendência — existe — veja Fases de um lançamento.
Base URL
https://api.fullcashbpo.com endereço da API
/api/v1 prefixo de todos os endpoints
/docs Swagger UI (testar no navegador)
/openapi.json contrato OpenAPI
/agente base completa para IAs geradoras de código
Autenticação
Toda chamada em /api/v1/* exige a chave no header:
Authorization: Bearer fc_live_xxxxxxxxxxxxxxxxxxxxxxxx
- As chaves são emitidas pela equipe FullCash (o cliente não cria chave).
- Cada chave enxerga uma ou mais empresas liberadas — nunca outra empresa, nunca outro módulo.
- Guardamos só o hash da chave. Se perder, geramos outra.
- Toda chave tem um usuário de integração próprio (
integration_user_id): um usuário técnico, sem login, com o nome que a FullCash definir (ex.: "Extranet Cliente X"). Ele assina o que a chave cria. Você não cria nem gerencia usuários pela API.
Headers usados na integração:
| Header | Direção | Para quê |
|---|---|---|
Authorization | você → API | Bearer fc_live_... em toda chamada |
X-FullCash-Company | você → API | empresa-alvo quando a chave tem várias |
Idempotency-Key | você → API | no POST /contas-pagar, evita duplicar |
x-request-id | API → você | id da requisição (mande para o suporte) |
Retry-After | API → você | quantos segundos esperar depois de um 429 |
X-FullCash-Event / X-FullCash-Delivery / X-FullCash-Signature | FullCash → seu webhook | nome do evento, id da entrega e assinatura |
Escolhendo a empresa
Se a chave acessa uma empresa, ela é implícita. Se acessa mais de uma, informe a empresa-alvo em cada request, por uma destas vias (nesta ordem):
- Header
X-FullCash-Company: <company_id> - Campo
company_idno corpo (POST) - Query
?company_id=<company_id>
Empresa fora do conjunto liberado → 403 empresa_nao_liberada.
Rotas de um lançamento (/contas-pagar/{id}, /mensagens, /anexos) não precisam da empresa: a API acha sozinha a dona do lançamento entre as empresas da chave. Se você informar, ela é respeitada (empresa errada → 404). Não chute empresa por empresa.
Homologação
Não existe ambiente separado: a homologação é feita na mesma API, com uma chave de teste que só enxerga empresas de teste (sem lançamento real nem operador real envolvido). Teste o fluxo completo nela — criar, anexar, conversar no chat e receber os webhooks — e só então passe a usar a chave das empresas reais. Os IDs (contas, fornecedores, centros…) de uma empresa não valem em outra: os da homologação respondem 404/422 com a chave de produção.
Escopos
A chave carrega escopos; sem o escopo, a resposta é 403 forbidden_scope.
| Escopo | Libera |
|---|---|
contas_pagar:read | listar/consultar lançamentos |
contas_pagar:write | criar lançamento |
cadastros:read | fornecedores, plano de contas, centros, contas bancárias, usuários, tipos de documento, regras de upload |
chat:read / chat:write | ler / escrever no chat da conta |
anexos:read / anexos:write | listar / enviar anexos (anexo numa mensagem exige chat:write e anexos:write) |
arquivos:read | ler e baixar os arquivos de todos os módulos (anexos, chat e pastas da equipe) |
Endpoints
Meta
GET /api/v1/me— empresas liberadas, escopos e rate limit da chave.
Lançamentos
GET /api/v1/contas-pagar— lista, dadatamais recente para a mais antiga. Filtros:busca(parte do título ou do código, ex.:CP2026),status_documento,fornecedor_id,data_de,data_ate,valor_min,valor_max,page,size.POST /api/v1/contas-pagar— cria (ver corpo abaixo). Idempotente com headerIdempotency-Key.GET /api/v1/contas-pagar/{id}— consulta um lançamento.POST /api/v1/contas-pagar/{id}/reenviar-analise— responde a Pendência: a conta volta dependenciasparaem_analise(o botão "Reenviar para análise" da tela). Corpo opcional:mensagem(a resposta, vai pro chat antes do aviso; precisa dechat:write) eautor_externoouuser_id(quem reenviou). O chat ganha o aviso "🔄 Conta Reenviada para Análise", a equipe é notificada e saiconta.mudou_fase. Responde200 { conta, mensagem }. Conta em outra fase →409 conta_fora_de_pendencia(details.status_documento;em_analise= já foi reenviada, não repita). Escopocontas_pagar:write. Só escrever no chat não tira a conta da Pendência.POST /api/v1/contas-pagar/analisar-documento— leitura por IA de NF/boleto (multipart/form-data, campofile; PDF ou imagem JPEG/PNG/WebP; opcionaltipo_transacao=saida(padrão) ouentrada). Devolve os campos extraídos (valor, datas, nº do documento, meio de pagamento, parcelamento…) e as sugestões já resolvidas:fornecedor.fornecedor_id(quando o CNPJ/CPF casa com o cadastro) eplano_conta_sugerido.plano_conta_id. Não cria nada — use o retorno para montar oPOST /contas-pagar(e confira antes de enviar). Escopocontas_pagar:write. Erros:422 documento_ilegivel,502 ia_indisponivel/ia_falhou.
Cadastros de apoio (para mandar IDs válidos)
GET /api/v1/cadastros/fornecedores?termo=— da empresa + gerais.GET /api/v1/cadastros/plano-contas?termo=— só folhas (nivel=conta).GET /api/v1/cadastros/centros-custo— só os vinculados à empresa.GET /api/v1/cadastros/contas-bancarias— só as da empresa.GET /api/v1/cadastros/usuarios— usuários ativos da empresa (sem e-mail). Só é necessário se você for usaruser_idno chat; para o caso comum, useautor_externo.GET /api/v1/cadastros/tipos-documento— listas fechadas de tipo de documento e meio de pagamento aceitas no lançamento (mesmas da tela do FullCash).GET /api/v1/cadastros/upload-regras— tamanho máximo (hoje 10 MB) e formatos/MIME aceitos nos anexos da conta e do chat. Consulte antes de enviar arquivo.
Chat da conta
GET /api/v1/contas-pagar/{id}/mensagensPOST /api/v1/contas-pagar/{id}/mensagens— corpo{ "message": "...", "autor_externo": { "nome": "..." } }. Conta finalizada (status_documento=validado, rótulo "Finalizado") é somente consulta, igual na tela: mensagem nova →409 conta_finalizada(a FullCash reabre se precisar).
Quem é o autor. Toda chave tem um usuário de integração próprio (sem login, nome definido pela FullCash, ex.: "Extranet Cliente X") que assina o que chega pela API. Pra dizer quem escreveu de verdade:
| Caso | O que mandar | Aparece no FullCash como |
|---|---|---|
| Recomendado — qualquer pessoa do seu sistema | autor_externo (só nome é obrigatório) | "Murillo Guimarães · via Extranet Cliente X" |
| Opcional — a pessoa tem conta no FullCash e você quer que conte como dela | user_id (de GET /cadastros/usuarios, vinculado à empresa) | "Murillo Guimarães", igual a uma mensagem da tela |
| Nenhum dos dois | — | "Extranet Cliente X" |
{ "message": "Pode seguir com o pagamento",
"autor_externo": { "nome": "Murillo Guimarães", "email": "murillo@cliente.com", "id": "id-no-seu-sistema" } }
Não precisa criar nem mapear usuário pra usar o autor_externo. user_id e autor_externo juntos → 422; user_id que não é da empresa → 422. O GET /mensagens devolve autor_externo em cada mensagem (ou null), da mais antiga para a mais nova. Mensagens com message_type diferente de user são avisos automáticos do FullCash (ex.: mudança de fase) — mostre como aviso, não como conversa. Chave antiga sem usuário de integração e sem user_id → 422 (peça pra FullCash configurar).
POST /api/v1/contas-pagar/{id}/mensagens/{msgId}/anexos— anexa um arquivo a uma mensagem do chat (multipart/form-data, campofile). É o caminho para mandar arquivo depois que a conta já foi criada. Escoposchat:write+anexos:write. Só na mensagem que a sua chave acabou de mandar, até 2 minutos depois dela. Mensagem antiga, escrita pelo operador na tela ou de outra chave →409 anexo_fora_da_janela(details.motivo:janela_expiradaoumensagem_de_outra_origem): mande uma mensagem nova com o arquivo. Conta finalizada (status_documento=validado) →409 conta_finalizada. Fluxo:POST /mensagens→ pega oid→ anexa logo em seguida.
Anexos
GET /api/v1/contas-pagar/{id}/anexos— devolve URLs assinadas temporárias.- Visualizar sem baixar (
preview_url) — todo anexo de imagem (JPG, PNG, WebP, GIF) ou PDF, aqui e nos anexos deGET /mensagens, traz umpreview_url: link fixo, válido por 30 dias e enquanto a chave estiver ativa. Use direto em<img src>/<iframe src>(não levaAuthorization) — o arquivo não precisa trafegar pela sua integração nem ser guardado de novo do seu lado. Revogou a chave → todos os links dela param. Outros tipos vêm compreview_url: null(use ourl, 1 h). GET /api/v1/anexos/{id}/ver?t=<token>— é a rota dopreview_url(venha sempre pelo link pronto; não monte o tokent). Respostas:302para o arquivo ·404sem dizer o motivo (token inválido, chave revogada ou anexo de outra empresa) ·410 link_expirado(passou dos 30 dias — busque um link novo noGET /mensagensouGET /anexos).POST /api/v1/contas-pagar/{id}/anexos—multipart/form-data, campofile. Só na criação: até 2 minutos depois de criada a conta. Passou disso →409 anexo_apos_lancamento; envie o arquivo pelo chat (escreva a mensagem e anexe em/mensagens/{msgId}/anexos). Exige que a chave tenha usuário de integração configurado (senão422).
Fluxo recomendado para criar com documento: POST /contas-pagar → logo em seguida POST /contas-pagar/{id}/anexos com a NF/boleto.
Arquivos (todos os módulos, só leitura e download)
Os anexos e os arquivos enviados nos chats de todos os módulos (Fechamento de Caixa, Cofre, Contas a Pagar, Agendamento, Conciliação, Solicitações) e as pastas criadas pela equipe, no mesmo modelo do módulo de Arquivos do FullCash: as pastas param no ano (Módulo → Ano) e, dentro do ano, vem a lista com filtros. Escopo arquivos:read.
GET /api/v1/arquivos/pastas— sem parâmetros: os módulos; commodulo: os anos. Cada item trazfiltro; o do ano ({ modulo, ano }) vai direto na lista e nas facetas.GET /api/v1/arquivos— lista paginada (page,sizeaté 200). Filtros combináveis:modulo+ano(+mes, oudia=AAAA-MM-DD),registro_tipo+registro_id,pasta_id(+incluir_subpastas=true),origem(arquivos= anexo,chat= enviado numa mensagem),enviado_por(id de quem enviou),busca(parte do nome do arquivo) e períododesde/ate. Ordem:ordem=enviado_em(padrão, mais recentes primeiro),data(data do registro — use para separar por mês/dia como a tela),nome,tamanho,registrooupor;desc=falseinverte. Traztotaletotal_bytesdo filtro inteiro. Sem link de download.GET /api/v1/arquivos/facetas?modulo=&ano=(ou?pasta_id=) — as opções dos filtros com contagem: meses, registros, quem enviou e origens. Monte os seus filtros a partir dela.GET /api/v1/arquivos/{id}— um arquivo, comurlassinada válida por 1 hora.POST /api/v1/arquivos/zip— baixa vários de uma vez num.zip. Corpo JSON com os mesmos filtros da lista, ouchaves(as linhas marcadas,"<id>|<registro.id>|<origem>"), enome. Dentro do.zipvem uma pasta só, com onomepedido, e todos os arquivos direto nela (nome repetido ganha " (2)"); pasta da equipe mantém as subpastas da equipe. Limite: 500 arquivos ou 1 GB — passou,413 limite_zipcom a contagem emdetails."somente_conferir": truedevolve só{ arquivos, bytes }.GET /api/v1/arquivos/pastas-equipe?parent_id=— pastas criadas pela equipe; os arquivos de uma pasta saem emGET /api/v1/arquivos?pasta_id={id}.
Pela API, Arquivos é só ler e baixar: não dá para criar, renomear ou apagar pasta, nem enviar ou apagar arquivo — isso é feito pela equipe dentro do FullCash.
Vários registros no mesmo dia (ex.: dois fechamentos em 30/09, cada um com anexo e arquivo de chat): cada linha da lista traz o seu registro e a origem, então nada se mistura. Para o dia inteiro: GET /api/v1/arquivos?modulo=fechamento-caixa&dia=2026-09-30 e agrupe por registro.id.
Regras: só aparecem os módulos ligados na empresa; itens de uso interno nunca aparecem; os chats de grupo da empresa ficam de fora. A data é a do registro (dia do fechamento, vencimento…), não a do envio. Um anexo do lote de agendamento aparece em cada item do lote (do_lote: true) — por isso o .zip dos selecionados usa a linha (chaves), não só o id.
Compatibilidade: os níveis antigos de /pastas (ano → meses, mes → dias, dia → registros) continuam respondendo como antes.
# 1) módulos e os anos de um módulo
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas"
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas?modulo=contas-pagar"
# 2) dentro do ano: opções dos filtros e a lista de outubro, pela data do registro
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/facetas?modulo=contas-pagar&ano=2026"
curl -H "Authorization: Bearer $FC_KEY" \
"$BASE/api/v1/arquivos?modulo=contas-pagar&ano=2026&mes=10&ordem=data"
# 3) um arquivo (link de 1 h) ou o mês inteiro num .zip
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/<arquivo_id>"
curl -X POST -H "Authorization: Bearer $FC_KEY" -H "Content-Type: application/json" \
-d '{"modulo":"contas-pagar","ano":2026,"mes":10,"nome":"CP outubro"}' \
-o cp-outubro.zip "$BASE/api/v1/arquivos/zip"
Criar um lançamento
curl -X POST https://api.fullcashbpo.com/api/v1/contas-pagar \
-H "Authorization: Bearer fc_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f3c-uma-chave-unica-por-lancamento" \
-d '{
"tipo_transacao": "saida",
"status": "a_pagar",
"valor": 1250.90,
"data": "2026-09-10",
"titulo": "NF 12345 — Fornecedor X",
"fornecedor_id": "UUID_DO_FORNECEDOR",
"plano_conta_id": "UUID_DE_UMA_FOLHA_DO_PLANO",
"centro_custo_id": "UUID_DE_CENTRO_DA_EMPRESA",
"parcelas": [
{ "numero": 1, "total": 2, "vencimento": "2026-10-05", "valor": 625.45 },
{ "numero": 2, "total": 2, "vencimento": "2026-11-05", "valor": 625.45 }
]
}'
Campos
Obrigatórios: titulo, valor (> 0) e data (YYYY-MM-DD). Todo o resto é opcional.
| Campo | O que é |
|---|---|
tipo_transacao | saida (padrão), entrada ou transferencia |
status | situação financeira: a_pagar, paga, a_receber, recebida (não é a fase) |
descricao | texto livre (ex.: dados de fornecedor ainda não cadastrado) |
fornecedor_id, plano_conta_id, centro_custo_id | IDs dos cadastros de apoio |
conta_bancaria_id | conta da empresa (saída/entrada) |
conta_origem_id / conta_destino_id | só em transferencia: as duas obrigatórias e diferentes |
numero_documento | nº da NF/boleto |
competencia | YYYY-MM ou MM/YYYY |
data_emissao | data de emissão do documento |
data_liquidacao | data do pagamento; só vale com status paga/recebida (sem ela, usa data) |
tipo_documento, meio_pagamento | um valor das listas de GET /cadastros/tipos-documento |
historico | histórico do lançamento |
codigo_barras | linha digitável do boleto |
parcelas | lista de { numero, total, vencimento, valor }: numero (1…N), total (N), vencimento (YYYY-MM-DD), valor. Vazio = parcela única. A API não confere a soma: mande a soma igual a valor |
tem_rateio, rateio_tipos | marca o rateio e as dimensões (centro_custo, plano_conta) |
company_id | empresa-alvo (alternativa ao header) |
Resposta 201: { "conta": { ... } } com status_documento: "em_analise", created_via: "api" e o codigo de rastreio (ex.: CP20260007). O valor oficial de cada informação é o campo do lançamento (valor, data…); dados_avancados é só a leitura feita pela IA.
Regras de validação (segurança)
Todas checadas contra a empresa-alvo. Falha → 422 com o campo em details:
| Campo | Regra |
|---|---|
fornecedor_id | existe e é da empresa ou geral |
plano_conta_id | existe, ativo e é folha (nivel=conta) |
centro_custo_id | vinculado à empresa-alvo |
conta_bancaria_id, conta_origem_id, conta_destino_id | pertencem à empresa-alvo |
| transferência | exige origem e destino, diferentes entre si |
| formato | tipos e obrigatórios do corpo (os problemas vêm em details) |
Fornecedor ainda não cadastrado
fornecedor_id é opcional e a API não cadastra fornecedor. Se o fornecedor não aparece em /cadastros/fornecedores, crie o lançamento sem fornecedor_id e informe nome e CPF/CNPJ na descricao. O operador cadastra e vincula na análise.
Fases de um lançamento
O campo status_documento diz em que fase do fluxo o lançamento está. Todo lançamento criado pela API nasce em em_analise; as demais transições são feitas pelo operador FullCash — menos a volta da Pendência (pendencias → em_analise), que é do cliente: POST /api/v1/contas-pagar/{id}/reenviar-analise.
⚠️ Use sempre a chave, nunca o rótulo da tela. Por razão histórica, duas chaves têm rótulo trocado:
finalizadoaparece como Validado evalidadoaparece como Finalizado.
Chave (status_documento) | Rótulo na tela | Significado |
|---|---|---|
em_analise | Em Análise | Recebido; o operador está conferindo. Toda conta nasce aqui. |
pendencias | Pendências | Falta informação ou há inconsistência; voltou para o cliente responder (pelo chat). |
finalizado | Validado | Conferido e aprovado pelo operador; aguarda o envio ao ERP. |
validado | Finalizado | Lançado no ERP. Fim do fluxo. |
rejeitado | Rejeitado | Recusado (inconsistência, prazo ou decisão de uma das partes). |
Caminho normal: em_analise → finalizado → validado.
Transições possíveis:
em_analise→finalizado(operador validou)em_analiseoufinalizado→pendencias(operador devolveu ao cliente)pendencias→em_analise(cliente reenviou — pela tela ou peloPOST /api/v1/contas-pagar/{id}/reenviar-analise— ou o operador retomou)finalizado→validado(saiu num lote e foi lançado no ERP)- qualquer fase →
rejeitado finalizado,validadoourejeitado→em_analise(reabertura pela equipe FullCash)
Toda mudança de fase emite o webhook conta.mudou_fase com de e para.
Respondendo uma Pendência (fluxo):
- chega
conta.mudou_fasecompara: "pendencias"; - leia o chat (
GET /api/v1/contas-pagar/{id}/mensagens) pra ver o que falta; - resolva e chame
POST /api/v1/contas-pagar/{id}/reenviar-analisecom a resposta emmensagem(arquivo? anexe na mensagem devolvida, em até 2 min); - chega
conta.mudou_fasecomde: "pendencias",para: "em_analise".
Situação de pagamento é outro campo. Não existe fase "agendado" ou "pago": isso está em status (a_pagar | paga | a_receber | recebida), independente da fase. Mudança em status emite conta.atualizada (não mudou_fase); consulte GET /api/v1/contas-pagar/{id} para ler o valor atual.
Correção de um lançamento já criado. A API não altera lançamentos. Peça a correção pelo chat da conta (POST /api/v1/contas-pagar/{id}/mensagens); o operador ajusta enquanto a conta está em em_analise ou pendencias.
Erros
Formato único:
{
"error": { "code": "validation_error", "message": "...", "details": [] },
"request_id": "uuid"
}
| HTTP | code | quando |
|---|---|---|
| 400 | bad_request / empresa_obrigatoria | request malformado / falta escolher empresa |
| 401 | invalid_key | chave ausente, errada, revogada ou expirada |
| 403 | forbidden_scope / empresa_nao_liberada | sem escopo / empresa fora da chave |
| 404 | not_found | não existe ou não é de uma empresa da chave (não vaza existência) |
| 409 | idempotency_conflict | mesma Idempotency-Key com corpo diferente |
| 409 | idempotency_in_progress | a 1ª requisição com essa chave ainda está criando; tente de novo em instantes |
| 409 | anexo_apos_lancamento | anexo na conta depois da janela de 2 min — envie pelo chat |
| 409 | conta_fora_de_pendencia | reenviar para análise uma conta que não está em Pendência (em_analise = já foi reenviada) |
| 409 | anexo_fora_da_janela | anexo no chat em mensagem que não é da sua chave ou com mais de 2 min — mande mensagem nova com o arquivo |
| 409 | conta_finalizada | mensagem ou anexo no chat com a conta finalizada (somente consulta) — peça para a FullCash reabrir |
| 410 | link_expirado | preview_url vencido (30 dias) — pegue um novo no GET |
| 413 | limite_zip | .zip passaria de 500 arquivos ou 1 GB |
| 413 | corpo_grande | requisição grande demais: upload acima de 11 MB (arquivo até 10 MB) ou JSON acima de 1 MB |
| 422 | validation_error | regra de negócio (fornecedor/plano/centro inválido, arquivo fora das regras de upload, chave sem usuário de integração) |
| 422 | documento_ilegivel | a IA não conseguiu ler o documento |
| 429 | rate_limited | teto por minuto (respeite Retry-After) |
| 500 | internal | erro inesperado do nosso lado — repita com espera e mande o request_id ao suporte |
| 502 | ia_indisponivel / ia_falhou | serviço de leitura por IA fora ou com erro; tente de novo |
| 503 | db_unavailable | API sem conexão com o banco — repita com espera |
| outro | http_error | erro HTTP genérico do servidor (raro); trate pelo status |
Guarde o request_id: ele casa com o log de auditoria do FullCash.
Idempotência
No POST, envie Idempotency-Key única por lançamento. Reenvio com a mesma chave devolve a mesma resposta (não duplica). Mesma chave com corpo diferente → 409 idempotency_conflict.
- Validade: a chave não expira. Fica registrada de forma permanente, separada por chave de API. Use um identificador estável do seu lado (ex.: o id do chamado ou do documento no seu sistema).
- Criação que falhou (ex.:
422) libera a chave: dá para reenviar, corrigido, com a mesmaIdempotency-Key. - Duas requisições simultâneas com a mesma chave: só uma cria; a outra recebe
409 idempotency_in_progresse deve tentar de novo em instantes.
Webhooks
Quando ativados, o FullCash faz POST na URL cadastrada quando algo muda.
Cadastro. É feito pela equipe FullCash, por chave de API. Informe a URL (HTTPS) e os eventos desejados; devolvemos o segredo (whsec_...) usado na assinatura. O segredo é mostrado uma vez só — guarde-o com segurança.
Eventos e o que vem em data:
| Evento | Quando | data |
|---|---|---|
conta.criada | lançamento criado (API ou tela) | conta_id, codigo, titulo, valor, status_documento, created_via |
conta.mudou_fase | status_documento mudou (qualquer transição) | conta_id, de, para |
conta.atualizada | outro campo mudou, sem troca de fase | conta_id, status_documento |
conta.mensagem.nova | nova mensagem no chat da conta | conta_id, message_id |
conta.anexo.novo | novo anexo do lançamento (não do chat) | conta_id, anexo_id |
- Os eventos disparam independente da origem: valem tanto para o que entra pela API quanto para o que o operador faz na tela do FullCash (emissão por trigger de banco). O que você mesmo criou também gera evento: use o
conta_id/message_idpra ignorar. - Arquivo enviado numa mensagem do chat chega em
conta.mensagem.nova(e aparece emanexosnoGET /mensagens), não emconta.anexo.novo. - O evento traz só o essencial; para o estado completo, consulte
GET /api/v1/contas-pagar/{id}. - Todo evento traz
company_idecompany_siglano topo do corpo: a loja dona do lançamento, pra você saber de quem é sem consultar nada. - Headers:
X-FullCash-Event(nome do evento),X-FullCash-Delivery(id da entrega) eX-FullCash-Signature(sha256=+ HMAC do corpo cru com o segredo). Valide a assinatura sempre, antes de fazer o parse do JSON. - Idempotência: cada evento tem
id; deduplique peloid. - Confirmação: responda HTTP 2xx. Qualquer outra resposta (ou falha de rede) gera nova tentativa: até 5 tentativas no total, com esperas de 1, 5, 30 e 120 minutos. Depois disso a entrega é marcada como falha — sem loop.
Corpo do evento (exemplo):
{ "id": "uuid-do-evento", "event": "conta.mudou_fase", "created_at": "2026-09-18T12:00:00Z", "company_id": "uuid-da-empresa", "company_sigla": "14A1", "data": { "conta_id": "uuid", "de": "em_analise", "para": "finalizado" } }
Exemplo de verificação (Node):
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
const a = Buffer.from(expected), b = Buffer.from(signatureHeader)
return a.length === b.length && timingSafeEqual(a, b)
}
Limites e boas práticas
- Rate limit por chave (padrão 100/min). Trate
429comRetry-After. - Quando repetir uma chamada que falhou:
| Resposta | Repetir? |
|---|---|
4xx (400, 401, 403, 404, 409, 410, 413, 422) | Não. O pedido está errado e vai falhar igual. Corrija o dado (veja error.message) ou registre o erro e siga. 410 = pegue um link novo. |
429 | Sim, depois do Retry-After. |
5xx ou falha de rede | Sim, com espera crescente (ex.: 1, 5, 30 min) e teto de tentativas (ex.: 5). Depois disso, marque como falha e avise alguém. |
Mande Idempotency-Key nos POST pra repetir sem risco de duplicar.
- Use o webhook, não fique consultando. O FullCash avisa em segundos quando um lançamento é criado, muda de fase ou recebe mensagem. Consultar a lista a cada poucos segundos não traz nada a mais e gasta seu rate limit. Se quiser uma rede de segurança, uma conferência a cada 15–30 min (filtrando por data) é suficiente.
- Paginação:
page/size(padrão 50; máx 200, ou 1000 em fornecedores e plano de contas); usetotalpara paginar. - Sempre resolva
fornecedor_id/plano_conta_id/centro_custo_idpelos endpoints de cadastros antes de criar — não invente IDs.
FullCash · API de Contas a Pagar · Swagger · openapi.json