o que é uma parcela
a integração trabalha no nível da parcela, não do título. um título com três parcelas vira três requisições, todas com o mesmoreceivableCode e installmentNumber diferente.
fluxo principal
1
criar a nota fiscal
toda parcela pertence a uma nota fiscal, então a nota precisa existir na teceo antes da conta a receber.
2
criar cada parcela
envie uma requisição por parcela do título. guarde o
id devolvido.3
anexar o boleto
vincule o PDF à parcela, por url ou enviando o binário.
endpoints
os campos de cada rota, com tipo, obrigatoriedade e exemplo, estão na página da própria rota, no menu ao lado. a listagem é paginada por cursor, como descrito em paginação.
regras de negócio
identificando o cliente e a nota
a parcela pede uma referência de cliente, porcustomerCode ou customerCnpj, e uma de nota, por invoiceId ou invoiceAccessKey. envie uma de cada par, com o mesmo valor que está no cadastro da teceo. a teceo não confere se o cliente da parcela é o mesmo da nota, então essa coerência fica com o seu sistema.
o que identifica a parcela
quem identifica a parcela é ointegrationCode, que é único dentro da marca. o receivableCode agrupa as parcelas do mesmo título, e o installmentNumber só indica a posição, sem checagem de duplicidade. reenviar o mesmo integrationCode é recusado com 409, e a API não altera a parcela depois de criada, então status e valores ficam como foram enviados. a teceo também não muda o status para OVERDUE quando a parcela vence.
criação
a criação grava a parcela e o primeiro registro do histórico dela. oid devolvido é o que o anexo do boleto pede como installmentId. se ele se perder, a listagem filtrada pelo integrationCode devolve a parcela com o mesmo id.
boleto
- envie
urloufile, nunca os dois e nunca nenhum - o tamanho máximo é 10 MiB nas duas formas. por
file, acima de 20 MiB o parser recusa antes de chegar na aplicação, com413 - o conteúdo é conferido pela assinatura do arquivo, então precisa ser um PDF de verdade, independente do nome
- o download da url tem timeout de 10 segundos
- o arquivo é re-hospedado pela teceo, que passa a servi-lo em
pdfUrl - reenviar o boleto gera uma url nova e apaga o arquivo anterior. não existe versionamento, então quem guardou a url antiga perde o acesso a ela
- a resposta não devolve a url final do arquivo. a
pdfUrlaparece na listagem de parcelas
erros
ao criar a parcela
ao anexar o boleto
o
code acompanha os erros de regra de negócio listados aqui. o 413 vem do parser de upload, e os 400 de validação de payload também chegam sem ele, só com status e message.