> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teceo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# integração de contas a receber

> a integração de contas a receber envia para a teceo as parcelas dos títulos gerados pelo faturamento, com vencimento, valores, meio de pagamento e boleto

## 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 mesmo `receivableCode` e `installmentNumber` diferente.

```mermaid theme={null}
graph LR
    NF["nota fiscal<br/>accessKey"] --> T["título<br/>receivableCode"]
    T --> P1["parcela 1<br/>integrationCode"]
    T --> P2["parcela 2<br/>integrationCode"]
    T --> P3["parcela 3<br/>integrationCode"]
    P1 --> B["boleto em PDF"]
```

## fluxo principal

<Steps>
  <Step title="criar a nota fiscal">
    toda parcela pertence a uma [nota fiscal](/integracoes/brand/notas-fiscais/overview), então a nota precisa existir na teceo antes da conta a receber.
  </Step>

  <Step title="criar cada parcela">
    envie uma requisição por parcela do título. guarde o `id` devolvido.
  </Step>

  <Step title="anexar o boleto">
    vincule o PDF à parcela, por url ou enviando o binário.
  </Step>
</Steps>

## endpoints

| endpoint | o que faz |
| - | - |
| `POST /v1/accounts-receivable` | cria uma parcela do título e devolve o `id` dela |
| `GET /v1/accounts-receivable` | lista as parcelas, com filtro por título, cliente, situação e faixa de datas |
| `PUT /v1/accounts-receivable/{installmentId}/attachments/pdf` | vincula o boleto em PDF à parcela |

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](/integracoes/brand/paginacao).

## regras de negócio

### identificando o cliente e a nota

a parcela pede uma referência de cliente, por `customerCode` 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 é o `integrationCode`, 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. o `id` 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 `url` **ou** `file`, 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, com `413`
* 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 `pdfUrl` aparece na listagem de parcelas

## erros

### ao criar a parcela

| status | código | quando acontece |
| - | - | - |
| `409` | `api.exception.accountsReceivable.alreadyExists` | já existe uma parcela sua na teceo com esse `integrationCode` |
| `400` | `api.exception.accountsReceivable.paymentDateRequired` | o status é `PAID` e `paymentDate` não foi enviada |
| `400` | - | faltou a referência do cliente ou a da nota. a recusa vem da validação do payload, então não traz `code` |
| `404` | `api.exception.invoiceNotFound` | a nota referenciada não existe na sua base na teceo |
| `404` | `api.exception.customerNotFound` | o cliente referenciado não existe na sua base na teceo |

### ao anexar o boleto

| status | código | quando acontece |
| - | - | - |
| `400` | `api.exception.accountsReceivable.attachmentUrlOrFileRequired` | nenhuma ou as duas fontes foram enviadas |
| `400` | `api.exception.accountsReceivable.attachmentTooLarge` | o arquivo passa de 10 MiB |
| `400` | `api.exception.accountsReceivable.attachmentDownloadFailed` | a url não respondeu, estourou o timeout ou devolveu erro |
| `400` | `api.exception.accountsReceivable.attachmentInvalidType` | o conteúdo não é um PDF |
| `404` | `api.exception.accountsReceivable.installmentNotFound` | a parcela não existe na sua base na teceo |
| `413` | - | o arquivo enviado em `file` passa de 20 MiB |

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`.

## exemplo de fluxo completo

```mermaid theme={null}
sequenceDiagram
    participant ERP as seu sistema
    participant API as teceo API

    ERP->>API: POST /v1/invoices
    API-->>ERP: id da nota

    ERP->>API: POST /v1/accounts-receivable
    API-->>ERP: id da parcela 1

    ERP->>API: POST /v1/accounts-receivable
    API-->>ERP: id da parcela 2

    ERP->>API: PUT /v1/accounts-receivable/{installmentId}/attachments/pdf
    API-->>ERP: boleto vinculado
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.