# Criar serviços

> Como criar um serviço com peças a partir do seu sistema, enviá-lo para otimização e acompanhar o resultado por webhook.

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

A sua integração pode criar um [serviço](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#servico) da central com as peças já definidas no seu sistema. O Cortecloud cadastra o marceneiro, preenche as peças, envia o serviço para otimização e gera o orçamento, como num serviço criado pelo app.

Rota: [`POST /services`](https://apis.cortecloud.com.br/docs/swagger#/Services/createService). Exige autenticação por central ([HMAC](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md)); com autenticação Basic, responde `401`.

## Corpo {#corpo}

```json
{
  "serviceInternalCode": "PED-123",
  "productionInternalCode": "LINHA-1",
  "carpenterEmail": "marceneiro@example.com",
  "carpenterName": "Fulano Marceneiro",
  "carpenterInternalCode": "CLI-9",
  "parts": [
    {
      "quantity": 1,
      "c": 500,
      "l": 500,
      "function": "Lateral",
      "complement": "Balcao A",
      "client": "Ana",
      "furniture": "Cozinha",
      "material": { "internalCode": "MDF18BR" },
      "c1": { "internalCode": "FT04BR" },
      "c2": null,
      "l1": null,
      "l2": null,
      "machining": {
        "x": 500,
        "y": 500,
        "z": 18,
        "startSide": 0,
        "horizontalDrills": [],
        "verticalDrills": [
          { "corner": 0, "bolthole": false, "x": 25, "y": 37, "depth": 12, "diameter": 15, "face": "i" }
        ],
        "furrowMachining": null,
        "furrowMachiningPair": null
      }
    }
  ]
}
```

| Campo | Regra |
| --- | --- |
| `serviceInternalCode` | [Código interno](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#codigo-interno) do serviço, normalmente o número do pedido no ERP. Opcional, até 255 caracteres. Volta nos webhooks como `service_internal_code`. |
| `productionInternalCode` | Código interno da linha de produção. Obrigatório. |
| `carpenterEmail`, `carpenterName` | E-mail e nome do marceneiro. Obrigatórios. |
| `carpenterInternalCode` | Código do marceneiro (cliente) no seu sistema. Obrigatório. |
| `parts` | Peças do serviço, de 1 a 500. |

Antes de criar o serviço, a rota cadastra o marceneiro no Cortecloud, caso ainda não exista, e o vincula à central com `carpenterInternalCode`, como no [login embutido](https://apis.cortecloud.com.br/docs/guias/login-embutido.md#novo-servico-para-um-vendedor). Se o marceneiro já tem vínculo ativo com a central, o código interno desse vínculo é mantido. Se `carpenterEmail` já pertence a um usuário de outro perfil (por exemplo, um vendedor), ele passa a ser marceneiro e perde o perfil anterior.

### Peças {#pecas}

`parts` segue a [estrutura da importação por arquivo JSON](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#estrutura-do-arquivo): os mesmos campos, as medidas em milímetros e o mesmo objeto `machining`, descrito em [Usinagem](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#usinagem). As diferenças estão nos materiais e na validação:

| Campo | Na importação | Aqui |
| --- | --- | --- |
| `material` | Nome da chapa no seu sistema. | Chapa da peça: `{ "internalCode": "..." }`, com o código interno da chapa na central. Obrigatório. |
| `client`, `furniture` | Não existem: o marceneiro escolhe o cliente na importação. | Cliente do marceneiro e ambiente da peça (por exemplo, "Cozinha"), até 255 caracteres cada. Opcionais: peças com o mesmo par ficam no mesmo cliente do serviço, e as peças sem eles ficam num cliente sem nome. |
| `c1`, `c2`, `l1`, `l2` | Nome da fita. | `{ "internalCode": "..." }` com o código interno da fita na central. Lado sem fita: `null` ou ausente. |
| `quantity`, `c`, `l` | A peça com valor ausente, zero ou negativo é descartada. | Valor ausente, zero ou negativo responde `400`. `c` e `l` vão até 9999.99. |

Os códigos internos de chapa e fita, `function` e `complement` têm até 255 caracteres; acima disso, a rota responde `400`.

Como os materiais chegam pelo código interno, não existe a etapa de [vínculo de materiais](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#vinculo-de-materiais) da importação.

Valem as mesmas regras da importação:

- `function` vazio vira "Peça".
- A usinagem só é aplicada se a linha de produção tiver máquina de usinagem (ver [Quando a linha de produção não usina](https://apis.cortecloud.com.br/docs/guias/importacao-json.md#quando-a-linha-de-producao-nao-usina)).
- Cada peça usa no máximo duas fitas diferentes. Se a central não aceita duas fitas por peça, os lados com a segunda fita ficam sem fita.

Não há campo para a rotação da peça: ela pode girar no plano de corte quando a chapa não tem veio.

## Resposta e acompanhamento {#resposta-e-acompanhamento}

A resposta `202` traz o `id` do serviço:

```json
{ "id": 98765 }
```

O `202` confirma o formato do corpo e o cadastro do marceneiro. Materiais, linha de produção e peças são validados depois, de forma assíncrona: um código de chapa inexistente, por exemplo, não muda a resposta. O resultado chega por [webhook](https://apis.cortecloud.com.br/docs/guias/webhooks.md#criacao-de-servico):

- `service.created`: o serviço foi criado e as peças foram gravadas (status `1`);
- `service.creation_failed`: a criação falhou, e `errors` traz os motivos.

O `service.created` sai depois que o serviço é enviado para otimização. Quando o orçamento fica pronto, chega o `service.quoted`. Se o envio for recusado, por exemplo por uma peça maior que a chapa, chega `service.creation_failed` com os motivos. Para receber os três, peça o cadastro de destinos para cada tipo (ver [Como ativar](https://apis.cortecloud.com.br/docs/guias/webhooks.md#como-ativar)).

Enquanto o Cortecloud preenche as peças, o serviço fica bloqueado para edição nos apps.

### Ids das peças {#ids-das-pecas}

O orçamento e as peças ficam em [`GET /services/{id}`](https://apis.cortecloud.com.br/docs/swagger#/Services/getService). `parts[].id` é o id de cada peça no Cortecloud: use-o para correlacionar as peças com o seu sistema, por exemplo com o `DrillCode` das usinagens.

## O que o marceneiro vê {#o-que-o-marceneiro-ve}

O serviço pertence à central e fica associado ao marceneiro. Ele aparece no Cortecloud do marceneiro a partir do status aprovado (`6`), só para leitura.

## Erros {#erros}

| Status | Quando |
| --- | --- |
| `400` | Corpo fora do formato: campo obrigatório ausente, e-mail inválido, `parts` vazio ou com mais de 500 peças, peça sem `material`, quantidade ou medida não positiva, `machining` fora do formato da importação. |
| `401` | Autenticação Basic. A rota exige HMAC. |

Erros nos materiais, na linha de produção ou nas peças, inclusive peça maior que a chapa, chegam pelo `service.creation_failed`, não na resposta.

:::caution Nova tentativa depois de timeout
`serviceInternalCode` não passa por checagem de duplicidade. Se a resposta se perder e a sua integração repetir a chamada, o Cortecloud pode criar o serviço duas vezes.
:::