{"_id":"572b6e766dbd9b1700c9e264","createdAt":"2016-05-05T16:01:58.462Z","link_url":"","parentDoc":null,"updates":[],"user":"54da5cb85b80b62300dadc4b","category":"54db48c86db3861700c840c5","hidden":false,"link_external":false,"next":{"description":"","pages":[]},"order":0,"version":"54da5d305b80b62300dadc51","title":"Visão geral da Rest API","type":"basic","__v":97,"api":{"auth":"required","params":[],"results":{"codes":[]},"settings":"","url":""},"body":"**Sumário:** A Clicksign é uma plataforma de assinatura eletrônica e digital de documentos que atende aos requisitos de integridade, autenticidade e não-repúdio da legislação brasileira. Saiba mais em http://www.clicksign.com.\nA API Rest da Clicksign é uma forma conveniente de enviar documentos para assinatura via integração com outros sistemas.\n\n### Conteúdo desta página:\n- [Ambientes / Hosts](/docs/visão-geral#ambientes--hosts)\n- [Autenticação](/docs/visão-geral#autenticao) \n- [Postman](/docs/visão-geral#postman) \n- [Bibliotecas disponíveis](/docs/visão-geral#bibliotecas-disponveis) \n- [Formato JSON](/docs/visão-geral#formato-json) \n- [Versões da API](/docs/visão-geral#verses-da-api) \n- [Formatação de datas](/docs/visão-geral#formatao-de-datas) \n- [Erros de requisições](/docs/visão-geral#erros-de-requisies) \n- [Protocolo TLS - Protocolos e cifras de segurança](/docs/visão-geral#ssltls-protocolos-e-cifras-de-segurana) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Ambientes / Hosts\"\n}\n[/block]\nA Clicksign possui duas infraestruturas completamente separadas, sendo que somente o ambiente `production` executa os processos para garantir que os documentos tenham validade jurídica. O ambiente `demo` serve como *sandbox* (ambiente de testes) para os desenvolvedores.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Ambiente\",\n    \"h-1\": \"Domínio\",\n    \"h-2\": \"Validade Jurídica\",\n    \"0-0\": \"Produção\",\n    \"1-0\": \"Desenvolvimento e demonstração (Sandbox)\",\n    \"0-1\": \"api.clicksign.com\",\n    \"1-1\": \"api.clicksign-demo.com\",\n    \"0-2\": \"`true`\",\n    \"1-2\": \"`false`\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Autenticação\"\n}\n[/block]\nA autenticação é feita através do parâmetro **access_token** que automaticamente identifica e autentica o usuário. O parâmetro deve ser enviado no **caminho** da requisição. Portanto, toda requisição deverá conter no _path_ \n`?access_token=string-do-token`.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Access Token\",\n  \"body\": \"Crie uma conta no ambiente de demonstração em https://desk.clicksign-demo.com. Faça acesso a esta conta e clique em Começar agora para habilitar o envio de documentos e criar o primeiro Cofre. Em seguida solicite o access_token através do e-mail [suporte:::at:::clicksign.com](mailto:suporte@clicksign.com).\"\n}\n[/block]\n### Exemplo de requisição\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Method\",\n    \"1-0\": \"Path\",\n    \"2-0\": \"Headers\",\n    \"0-1\": \"`GET`\",\n    \"1-1\": \"`/v1/documents?access_token=string-do-token`\",\n    \"2-1\": \"`Accept: application/json`\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Postman\"\n}\n[/block]\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/c5cce61508ed0d9e80f9#?env%5BClicksign%20-%20Demo%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkuY2xpY2tzaWduLWRlbW8uY29tIiwidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjY2Vzc190b2tlbiIsInZhbHVlIjoiIiwidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\nPostman é uma poderosa plataforma para tornar seu desenvolvimento de API mais rápido e mais fácil. Para utiliza-lo, basta clicar no botão acima. Após a instalação e importação da biblioteca \"Clicksign API\", é necessário configurar o **access_token** no canto superior direito conforme imagem abaixo:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c54e47c-2017-01-17_11-29-45.png\",\n        \"2017-01-17_11-29-45.png\",\n        432,\n        154,\n        \"#f8f8f8\"\n      ],\n      \"sizing\": \"smart\",\n      \"border\": false\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Bibliotecas disponíveis\"\n}\n[/block]\n- .NET em https://github.com/clicksign/clicksign-dotnet\n- Ruby em https://github.com/clicksign/clicksign-ruby\n- PHP em https://github.com/clicksign/clicksign-php\n- Java em https://github.com/clicksign/clicksign-java\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Formato JSON\"\n}\n[/block]\nA API da Clicksign utiliza `JSON` como formato das requisições. O formato deve ser passado através dos HTTP Headers: `Accept: application/json` e `Content-Type: application/json`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Versões da API\"\n}\n[/block]\nPara possibilitar a evolução contínua da API, a Clicksign implementa um sistema de versões. Dessa forma é necessário que as requisições contenham a versão da API que está sendo utilizada. Isto é feito através do path da requisição, por exemplo: `api.clicksign.com/v1/documents`.\n\nUma nova versão é lançada apenas quando há quebra de funcionalidade. Ou seja, melhorias, novas funcionalidades e correções de _bugs_, desde que não alterem o comportamento esperado, não implicam no lançamento de uma nova versão.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Formatação de datas\"\n}\n[/block]\nTodas as datas estão formatadas de acordo com a RFC3339, por exemplo: `2016-02-05T15:40:15.335-02:00`\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Erros de requisições\"\n}\n[/block]\n### Resposta 4XX\n\nCaso o cliente utilize parâmetros inválidos, o corpo da resposta será um `JSON` contendo uma mensagem de erro.\n\n- HTTP Header: `Content-Type: application/json`\n- Body: `{ \"message\": \"Invalid parameters.\" }`\n\n### Resposta 5XX\n\nCaso ocorra qualquer tipo de falha no servidor, o corpo da resposta será um `JSON` contendo uma mensagem de erro.\n\n- HTTP Header: `Content-Type: application/json`\n- Body: `{ \"message\": \"Server error.\" }`\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"SSL/TLS - Protocolos e cifras de segurança\"\n}\n[/block]\nToda a comunicação cliente/servidor é feita através de HTTP sobre TLS (HTTPS). Requisições em HTTP resultam em redirecionamentos (301) para o protocolo HTTPS.\n\nA plataforma Clicksign é compatível apenas com os protocolos **TLS 1**, **TLS 1.1** e **TLS 1.2** e com as cifras listadas abaixo:\n\n- ECDHE-ECDSA-AES128-GCM-SHA256\n- ECDHE-RSA-AES128-GCM-SHA256\n- ECDHE-ECDSA-AES128-SHA256\n- ECDHE-RSA-AES128-SHA256\n- ECDHE-ECDSA-AES128-SHA\n- ECDHE-ECDSA-AES256-GCM-SHA384\n- ECDHE-RSA-AES256-GCM-SHA384\n- ECDHE-ECDSA-AES256-SHA384\n- ECDHE-RSA-AES256-SHA384\n- ECDHE-ECDSA-AES256-SHA\n- AES128-GCM-SHA256\n- AES128-SHA256\n- AES256-GCM-SHA384\n- AES256-SHA256\n\nNota: a Clicksign não provê suporte ao protocolo **SSL**.\n\n**Servidores Linux / Unix:** É necessário que o **OpenSSL** seja **igual ou superior a versão 1.0.1 e 10.1** para ambientes **FreeBSD**.\n\n**Servidores Windows:** É necessário seguir as recomendações indicadas no seguinte artigo: https://support.microsoft.com/pt-br/kb/245030.\n\n**C#:** O protocolo TLS 1.2 é compatível com o .NET Framework 4.5. (https://msdn.microsoft.com/en-us/library/system.security.authentication.sslprotocols(v=vs.110).aspx)\nPara criação de um canal seguro, acrescentar as linhas abaixo:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;\\nServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, sslPolicyErrors) => true;\\n\\n/// Código enviado por Jonas Eduardo Araldi (http://sistemahiper.com.br/)\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]","isReference":false,"project":"54da5d2f5b80b62300dadc4e","sync_unique":"","excerpt":"","githubsync":"","slug":"visão-geral","childrenPages":[]}

Visão geral da Rest API


**Sumário:** A Clicksign é uma plataforma de assinatura eletrônica e digital de documentos que atende aos requisitos de integridade, autenticidade e não-repúdio da legislação brasileira. Saiba mais em http://www.clicksign.com. A API Rest da Clicksign é uma forma conveniente de enviar documentos para assinatura via integração com outros sistemas. ### Conteúdo desta página: - [Ambientes / Hosts](/docs/visão-geral#ambientes--hosts) - [Autenticação](/docs/visão-geral#autenticao) - [Postman](/docs/visão-geral#postman) - [Bibliotecas disponíveis](/docs/visão-geral#bibliotecas-disponveis) - [Formato JSON](/docs/visão-geral#formato-json) - [Versões da API](/docs/visão-geral#verses-da-api) - [Formatação de datas](/docs/visão-geral#formatao-de-datas) - [Erros de requisições](/docs/visão-geral#erros-de-requisies) - [Protocolo TLS - Protocolos e cifras de segurança](/docs/visão-geral#ssltls-protocolos-e-cifras-de-segurana) [block:api-header] { "type": "basic", "title": "Ambientes / Hosts" } [/block] A Clicksign possui duas infraestruturas completamente separadas, sendo que somente o ambiente `production` executa os processos para garantir que os documentos tenham validade jurídica. O ambiente `demo` serve como *sandbox* (ambiente de testes) para os desenvolvedores. [block:parameters] { "data": { "h-0": "Ambiente", "h-1": "Domínio", "h-2": "Validade Jurídica", "0-0": "Produção", "1-0": "Desenvolvimento e demonstração (Sandbox)", "0-1": "api.clicksign.com", "1-1": "api.clicksign-demo.com", "0-2": "`true`", "1-2": "`false`" }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Autenticação" } [/block] A autenticação é feita através do parâmetro **access_token** que automaticamente identifica e autentica o usuário. O parâmetro deve ser enviado no **caminho** da requisição. Portanto, toda requisição deverá conter no _path_ `?access_token=string-do-token`. [block:callout] { "type": "info", "title": "Access Token", "body": "Crie uma conta no ambiente de demonstração em https://desk.clicksign-demo.com. Faça acesso a esta conta e clique em Começar agora para habilitar o envio de documentos e criar o primeiro Cofre. Em seguida solicite o access_token através do e-mail [suporte@clicksign.com](mailto:suporte@clicksign.com)." } [/block] ### Exemplo de requisição [block:parameters] { "data": { "0-0": "Method", "1-0": "Path", "2-0": "Headers", "0-1": "`GET`", "1-1": "`/v1/documents?access_token=string-do-token`", "2-1": "`Accept: application/json`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Postman" } [/block] [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/c5cce61508ed0d9e80f9#?env%5BClicksign%20-%20Demo%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkuY2xpY2tzaWduLWRlbW8uY29tIiwidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjY2Vzc190b2tlbiIsInZhbHVlIjoiIiwidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlfV0=) Postman é uma poderosa plataforma para tornar seu desenvolvimento de API mais rápido e mais fácil. Para utiliza-lo, basta clicar no botão acima. Após a instalação e importação da biblioteca "Clicksign API", é necessário configurar o **access_token** no canto superior direito conforme imagem abaixo: [block:image] { "images": [ { "image": [ "https://files.readme.io/c54e47c-2017-01-17_11-29-45.png", "2017-01-17_11-29-45.png", 432, 154, "#f8f8f8" ], "sizing": "smart", "border": false } ] } [/block] [block:api-header] { "type": "basic", "title": "Bibliotecas disponíveis" } [/block] - .NET em https://github.com/clicksign/clicksign-dotnet - Ruby em https://github.com/clicksign/clicksign-ruby - PHP em https://github.com/clicksign/clicksign-php - Java em https://github.com/clicksign/clicksign-java [block:api-header] { "type": "basic", "title": "Formato JSON" } [/block] A API da Clicksign utiliza `JSON` como formato das requisições. O formato deve ser passado através dos HTTP Headers: `Accept: application/json` e `Content-Type: application/json`. [block:api-header] { "type": "basic", "title": "Versões da API" } [/block] Para possibilitar a evolução contínua da API, a Clicksign implementa um sistema de versões. Dessa forma é necessário que as requisições contenham a versão da API que está sendo utilizada. Isto é feito através do path da requisição, por exemplo: `api.clicksign.com/v1/documents`. Uma nova versão é lançada apenas quando há quebra de funcionalidade. Ou seja, melhorias, novas funcionalidades e correções de _bugs_, desde que não alterem o comportamento esperado, não implicam no lançamento de uma nova versão. [block:api-header] { "type": "basic", "title": "Formatação de datas" } [/block] Todas as datas estão formatadas de acordo com a RFC3339, por exemplo: `2016-02-05T15:40:15.335-02:00` [block:api-header] { "type": "basic", "title": "Erros de requisições" } [/block] ### Resposta 4XX Caso o cliente utilize parâmetros inválidos, o corpo da resposta será um `JSON` contendo uma mensagem de erro. - HTTP Header: `Content-Type: application/json` - Body: `{ "message": "Invalid parameters." }` ### Resposta 5XX Caso ocorra qualquer tipo de falha no servidor, o corpo da resposta será um `JSON` contendo uma mensagem de erro. - HTTP Header: `Content-Type: application/json` - Body: `{ "message": "Server error." }` [block:api-header] { "type": "basic", "title": "SSL/TLS - Protocolos e cifras de segurança" } [/block] Toda a comunicação cliente/servidor é feita através de HTTP sobre TLS (HTTPS). Requisições em HTTP resultam em redirecionamentos (301) para o protocolo HTTPS. A plataforma Clicksign é compatível apenas com os protocolos **TLS 1**, **TLS 1.1** e **TLS 1.2** e com as cifras listadas abaixo: - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES128-SHA256 - ECDHE-RSA-AES128-SHA256 - ECDHE-ECDSA-AES128-SHA - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-AES256-SHA384 - ECDHE-RSA-AES256-SHA384 - ECDHE-ECDSA-AES256-SHA - AES128-GCM-SHA256 - AES128-SHA256 - AES256-GCM-SHA384 - AES256-SHA256 Nota: a Clicksign não provê suporte ao protocolo **SSL**. **Servidores Linux / Unix:** É necessário que o **OpenSSL** seja **igual ou superior a versão 1.0.1 e 10.1** para ambientes **FreeBSD**. **Servidores Windows:** É necessário seguir as recomendações indicadas no seguinte artigo: https://support.microsoft.com/pt-br/kb/245030. **C#:** O protocolo TLS 1.2 é compatível com o .NET Framework 4.5. (https://msdn.microsoft.com/en-us/library/system.security.authentication.sslprotocols(v=vs.110).aspx) Para criação de um canal seguro, acrescentar as linhas abaixo: [block:code] { "codes": [ { "code": "ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;\nServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, sslPolicyErrors) => true;\n\n/// Código enviado por Jonas Eduardo Araldi (http://sistemahiper.com.br/)", "language": "csharp" } ] } [/block]