# API Pública do Cortecloud

> O que a API Pública do Cortecloud permite integrar, URLs dos ambientes de homologação e produção e primeiros passos.

URL canônica: https://apis.cortecloud.com.br/docs/

O Cortecloud é a plataforma em que **marceneiros**, profissionais que projetam e montam móveis, encomendam peças cortadas sob medida a **centrais de serviço**, as empresas que vendem os materiais e produzem essas peças. Neste portal, "central" é sempre a central de serviço. Os demais termos estão definidos em [Conceitos](https://apis.cortecloud.com.br/docs/comecando/conceitos.md).

A API Pública permite integrar o sistema de uma central (ERP, sistema de vendas, checkout de pagamento) ao Cortecloud. Com ela, a sua integração pode:

- manter preço, estoque e status ativo/inativo dos materiais da central: chapas, fitas de borda e componentes ([Materiais](https://apis.cortecloud.com.br/docs/guias/integracao-erp/materiais.md));
- consultar os serviços (pedidos) da central, associá-los aos pedidos do seu ERP e enviá-los para produção ([Obter serviços](https://apis.cortecloud.com.br/docs/guias/integracao-erp/obter-servicos.md) e [Atualizar serviços](https://apis.cortecloud.com.br/docs/guias/integracao-erp/atualizar-servicos.md));
- ser avisada a cada mudança de status de um serviço, sem consultar `GET /services` repetidamente ([Webhooks](https://apis.cortecloud.com.br/docs/guias/webhooks.md));
- receber o pagamento online de um serviço num checkout do seu sistema ([Checkout de pagamento](https://apis.cortecloud.com.br/docs/guias/checkout.md));
- abrir telas do Cortecloud já autenticadas para vendedores e marceneiros, sem que eles digitem usuário e senha ([Login embutido](https://apis.cortecloud.com.br/docs/guias/login-embutido.md)).

Para quem desenvolve software de projeto de móveis, o portal também documenta o formato do arquivo JSON com que o marceneiro importa peças, furações e usinagens para um serviço ([Importação por arquivo JSON](https://apis.cortecloud.com.br/docs/guias/importacao-json.md)). Essa integração é feita por arquivo e não usa a API.

## Ambientes {#ambientes}

| Ambiente | URL base |
| --- | --- |
| Homologação | `https://apis.hml.cortecloud.com.br` |
| Produção | `https://apis.cortecloud.com.br` |

Cada ambiente tem credenciais próprias. Os exemplos usam caminhos relativos (`/services`, `/materials/boards`): prefixe com a URL base do ambiente.

## Primeiros passos {#primeiros-passos}

1. Peça as credenciais (api key e secret key) a suporte@serrabits.com.br. Informe que você é integrador, qual central vai integrar e em qual ambiente. Se não souber o [código da central](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#codigo-da-central), peça-o na mesma mensagem.
2. Implemente a assinatura das requisições seguindo [Autenticação](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md) e confira o resultado com os [valores de validação](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md#valide-a-sua-implementacao).
3. Leia [Erros, limites e paginação](https://apis.cortecloud.com.br/docs/comecando/erros-limites-paginacao.md) antes de escrever laços de sincronização.
4. Siga o guia do seu caso de uso, primeiro em homologação e depois em produção.

## Como esta documentação está organizada {#como-esta-documentacao-esta-organizada}

- **Guias** (esta parte): conceitos, autenticação e o passo a passo de cada tipo de integração.
- **[Referência da API](https://apis.cortecloud.com.br/docs/swagger)**: Swagger com todas as rotas, parâmetros, corpos e respostas. É a fonte de verdade sobre o formato de cada rota; os guias apontam para a operação correspondente.
- **[Playground](https://apis.cortecloud.com.br/docs/playground.html)**: coleção do [Bruno](https://www.usebruno.com/) com uma requisição de exemplo para cada rota, no ambiente de homologação. Aberta no Bruno, a coleção assina cada requisição sozinha. Para usá-la:
  1. abra a coleção no Bruno pelo botão "Open in Bruno";
  2. ative o Developer Mode do Bruno (o script de assinatura usa o módulo `crypto`);
  3. no environment `HML`, preencha `apiKey` e `secretKey` como secrets e `companyInternalCode` com o código da central.