A rota GET /api/v1/receivables lista as contas a receber que a chave alcança, da mais próxima de vencer à mais distante. Para ler uma só, use GET /api/v1/receivables/{id}.
Antes de começar a ler as contas a receber pela API
A chave precisa da permissão Recebíveis · leitura (
receivable:read). As opções Só ler e Ler, lançar e dar baixa já incluem essa permissão.A chave só vê os grupos e as empresas que o administrador escolheu. Uma conta de outro grupo responde
404.
Passo a passo para ler as contas a receber pela API
Chame
GET https://developers.kamino.com.br/api/v1/receivablescom o período de vencimento emdueFromedueUntil, por exemplo?dueFrom=2026-08-01&dueUntil=2026-08-31, e o cabeçalhoAuthorization: Bearer pak_live_SUA_CHAVE.A resposta traz
data, com as contas, enextCursor.Enquanto
nextCursornão viernull, repita a chamada mandando o valor dele emcursor.
Filtros da listagem de contas a receber
status—PENDING,PARTIALLY_RECEIVEDouRECEIVED. Pode repetir.dueFromedueUntil— datasaaaa-mm-dd, sempre juntas, com até 366 dias entre elas.size— de 1 a 100 contas por página; o padrão é 25.archived—false(padrão),trueouonly.updatedSince— só o que mudou desde um instante, com fuso.companyIdeworkspaceId— restringem a uma empresa ou a um grupo.externalIdenumber— buscam uma conta pelo identificador do seu sistema ou pelo número; exigemworkspaceId.
Campos de cada conta a receber
Entre outros: id, reference, status, dueDate, grossAmount, settledAmount, balance, customerName, customerDocument, description, companyId e workspaceId. Para saber quanto está em aberto, use balance, e não grossAmount.
Limites da leitura de contas a receber pela API
Paginação por cursor. Não existe
page=2: siga onextCursor.Até 100 contas por página. Acima disso, a chamada recebe
422.600 chamadas por minuto por integração e ambiente.
Erros ao ler as contas a receber, e o que fazer
403 insufficient_scope— a chave não temreceivable:read. Peça ao administrador a permissão.422 invalid_parameter— um filtro está fora do permitido (sizeacima de 100,dueFromsemdueUntil, período acima de 366 dias). Corrija o parâmetro.404— a conta não existe nos grupos que a chave alcança.503 upstream_unavailable— o serviço não respondeu. Tente de novo em instantes.
Perguntas frequentes sobre ler contas a receber pela API
A API também lança contas a receber?
Lança, com as permissões de escrita. Veja a referência Contas a receber na Documentação da API.
Como pego só o que mudou desde a última leitura?
Use updatedSince com o instante da sua última leitura.