# Obter serviços

> Como listar serviços filtrando por status, código interno e data, e consultar o conteúdo completo de um serviço.

URL canônica: https://apis.cortecloud.com.br/docs/guias/integracao-erp/obter-servicos/

Um [serviço](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#servico) é um pedido de peças feito no Cortecloud, e corresponde a um pedido no seu ERP. O serviço fica visível para a sua integração a partir do orçamento gerado (`4`).

O fluxo usual é listar os serviços que interessam ao ERP e consultar cada um para obter o conteúdo completo. Para ser avisado das mudanças de status em vez de listar periodicamente, use [webhooks](https://apis.cortecloud.com.br/docs/guias/webhooks.md).

## Listar serviços {#listar-servicos}

Rota: [`GET /services`](https://apis.cortecloud.com.br/docs/swagger#/Services/listServices).

A listagem devolve, para cada serviço, `id`, `internal_code` e o objeto `status` com o código do status e as datas de cada etapa. O conteúdo completo (peças, materiais, valores) vem só na consulta individual.

Filtros aceitos na query string:

| Parâmetro | Uso |
| --- | --- |
| `status` | Códigos de status separados por vírgula. Aceita `4`, `25`, `6`, `7` e `9` (ver [status do serviço](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#status-do-servico)); sem o filtro, traz todos eles. Outros códigos são recusados com `400`. |
| `internal_code` | Traz só o serviço com esse código interno (o número do pedido no ERP). Com o valor `null`, traz só os serviços que ainda não têm código interno. |
| `date_start`, `date_end` | Filtram pela data da última alteração do serviço. `date_start` não pode ser posterior a `date_end`. |
| `limit`, `offset` | Paginação; ver [Erros, limites e paginação](https://apis.cortecloud.com.br/docs/comecando/erros-limites-paginacao.md#paginacao). |

Passos:

1. Chame `GET /services` com os filtros do seu caso. Para buscar pedidos novos para o ERP, por exemplo, combine `status=6` (aprovado) com `internal_code=null` (ainda sem pedido no ERP).
2. Processe os itens de `resource`.
3. Se `meta.next` não for nulo, repita a chamada com `offset` igual a `meta.next`. Esta rota aceita 1 requisição a cada 5 segundos: espere entre uma página e a próxima.
4. Quando `meta.next` vier nulo, a listagem acabou.

Exemplo de resposta:

```json
{
  "resource": [
    {
      "id": 123,
      "internal_code": null,
      "status": {
        "code": 6,
        "created_date": "…",
        "budgeted_date": "…",
        "purchased_date": "…",
        "authorized_date": null,
        "finished_date": null
      }
    }
  ],
  "meta": {
    "count": 1,
    "next": null
  }
}
```

As datas de `status` marcam cada etapa: criação (`created_date`), orçamento gerado (`budgeted_date`), aprovação (`purchased_date`), envio para produção (`authorized_date`) e fim da produção (`finished_date`). Etapas ainda não alcançadas vêm nulas.

## Consultar um serviço {#consultar-um-servico}

Rota: [`GET /services/{id}`](https://apis.cortecloud.com.br/docs/swagger#/Services/getService).

Devolve o conteúdo completo do serviço:

| Campo | Conteúdo |
| --- | --- |
| `status`, `history` | Status atual com as datas de cada etapa e o histórico de mudanças de status. O histórico inclui só as mudanças para orçamento gerado (`4`), aprovado (`6`), enviado para produção (`7`) e produzido (`9`). |
| `steps` | Datas das etapas da produção: corte, aplicação de fita, usinagem, embalagem e expedição. |
| `client` | Código interno do marceneiro na central (o código do cliente no seu ERP). |
| `labour` | Valores de mão de obra: corte, aplicação de fita, usinagem (com o resumo de furos e rasgos), embalagem e frete. |
| `materials` | Chapas, fitas de borda e componentes consumidos, com código interno, quantidade e preço. |
| `parts` | Lista de peças: medidas, quantidade, chapa, fita de borda aplicada em cada lado, furações e usinagens. |

Os códigos internos de `materials` e `parts` são os mesmos que a sua integração mantém pelas rotas de [materiais](https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais.md), o que permite casar cada item do serviço com o item do ERP.

Responde `404` quando o serviço não é encontrado. O formato completo de cada campo está na [operação no Swagger](https://apis.cortecloud.com.br/docs/swagger#/Services/getService).

## Próximo passo {#proximo-passo}

Depois de registrar o pedido no ERP, [associe o código do pedido ao serviço](https://apis.cortecloud.com.br/docs/guias/integracao-erp/atualizar-servicos.md).