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

# Pesquisar Contas a Pagar

> Serviço destinado a consultar contas a pagar.

## Endpoint

```
POST https://api.tiny.com.br/api2/contas.pagar.pesquisa.php
```

## Parâmetros

| Parâmetro             | Tipo   | Ocorrência  | Descrição                                                  |
| --------------------- | ------ | ----------- | ---------------------------------------------------------- |
| token                 | string | obrigatório | Chave gerada para identificar sua empresa                  |
| formato               | string | obrigatório | Formato do retorno (json)                                  |
| nome\_cliente         | string | opcional    | Nome do cliente (1)                                        |
| numero\_doc           | string | opcional    | Número do documento (1)                                    |
| data\_ini\_emissao    | string | opcional    | Data inicial de emissão (formato dd/mm/yyyy) (1)           |
| data\_fim\_emissao    | string | opcional    | Data final de emissão (formato dd/mm/yyyy) (1)             |
| data\_ini\_vencimento | string | opcional    | Data inicial de vencimento (formato dd/mm/yyyy) (1)        |
| data\_fim\_vencimento | string | opcional    | Data final de vencimento (formato dd/mm/yyyy) (1)          |
| situacao              | string | opcional    | Situação das contas (aberto, pago, cancelada, parcial) (1) |
| pagina                | int    | opcional    | Número da página (padrão: 1; 100 registros/página)         |

> (1) Ao menos um parâmetro entre nome\_cliente, numero\_doc e datas deve ser informado.

## Retorno

| Campo                                    | Tipo    | Tamanho | Ocorrência  | Descrição                                   |
| ---------------------------------------- | ------- | ------- | ----------- | ------------------------------------------- |
| retorno                                  | object  | -       | obrigatório | Elemento raiz do retorno                    |
| retorno.status\_processamento            | int     | -       | obrigatório | Conforme tabela "Status de Processamento"   |
| retorno.status                           | string  | -       | obrigatório | "OK" ou "Erro"                              |
| retorno.codigo\_erro                     | int     | -       | condicional | Conforme tabela "Códigos de erro"           |
| retorno.erros\[]                         | list    | -       | condicional | Lista dos erros encontrados \[0..n]         |
| retorno.erros\[].erro                    | string  | -       | condicional | Descrição do erro                           |
| retorno.pagina                           | int     | -       | obrigatório | Número da página retornada                  |
| retorno.numero\_paginas                  | int     | -       | obrigatório | Número de páginas do retorno                |
| retorno.contas\[]                        | list    | -       | condicional | Lista de resultados da pesquisa             |
| retorno.contas\[].conta.id               | int     | -       | condicional | Identificação da conta                      |
| retorno.contas\[].conta.nome\_cliente    | string  | 100     | condicional | Nome do cliente                             |
| retorno.contas\[].conta.historico        | string  | 300     | condicional | Histórico da conta a pagar                  |
| retorno.contas\[].conta.numero\_doc      | string  | 20      | condicional | Número do documento                         |
| retorno.contas\[].conta.data\_vencimento | date    | 10      | condicional | Data de vencimento (dd/mm/yyyy)             |
| retorno.contas\[].conta.data\_emissao    | date    | 10      | condicional | Data de emissão (dd/mm/yyyy)                |
| retorno.contas\[].conta.valor            | decimal | -       | condicional | Valor da conta                              |
| retorno.contas\[].conta.saldo            | decimal | -       | condicional | Saldo da conta                              |
| retorno.contas\[].conta.situacao         | string  | 30      | condicional | Situação (pago, cancelado, aberto, parcial) |

## Observações

* Por padrão, 100 registros são listados por página
* Utilize o parâmetro "pagina" para navegar entre páginas
* Datas utilizam formato dd/mm/yyyy (exemplo: "01/01/2012")
* Valores decimais usam "." (ponto) como separador (exemplo: "5.25")

## Exemplo de chamada

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/contas.pagar.pesquisa.php \
  -d "token=SEU_TOKEN&formato=json&nome_cliente=henrique teste&numero_doc=000453/01"
```

## Exemplos de retorno

### Erro - Token inválido

```json theme={null}
{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {
        "erro": "token invalido"
      }
    ]
  }
}
```

### Erro - Consulta sem registros

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 20,
    "erros": [
      {
        "erro": "A Consulta não retornou registros"
      }
    ]
  }
}
```

### Sucesso

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "pagina": 1,
    "numero_paginas": 1,
    "contas": [
      {
        "id": "5489125",
        "nome_cliente": "henrique teste 2",
        "historico": "Ref. a NF número 000453, henrique teste 2 (parcela 1/1)",
        "numero_doc": "000453/01",
        "data_vencimento": "08/07/2015",
        "data_emissao": "10/07/2015",
        "valor": "6.00",
        "saldo": "1.00",
        "situacao": "parcial"
      }
    ]
  }
}
```