diff --git a/MifielAPI/MifielAPI/Dao/Webhooks.cs b/MifielAPI/MifielAPI/Dao/Webhooks.cs new file mode 100644 index 0000000..3eb6938 --- /dev/null +++ b/MifielAPI/MifielAPI/Dao/Webhooks.cs @@ -0,0 +1,66 @@ +using MifielAPI.Objects; +using MifielAPI.Utils; +using System.Collections.Generic; +using System.Net.Http; +using System.Text; + +namespace MifielAPI.Dao +{ + /// + /// CRUD + trigger helpers for account-level webhooks. + /// See https://docs.mifiel.com/en/#tag/Webhooks + /// + public class Webhooks : BaseObjectDAO + { + private string _webhooksPath = "webhooks"; + + public Webhooks(ApiClient apiClient) : base(apiClient) { } + + public override void Delete(string id) + { + ApiClient.Delete(_webhooksPath + "/" + id); + } + + public override Webhook Find(string id) + { + HttpContent httpResponse = ApiClient.Get(_webhooksPath + "/" + id); + string response = httpResponse.ReadAsStringAsync().Result; + return MifielUtils.ConvertJsonToObject(response); + } + + public override List FindAll() + { + HttpContent httpResponse = ApiClient.Get(_webhooksPath); + string response = httpResponse.ReadAsStringAsync().Result; + return MifielUtils.ConvertJsonToObject>(response); + } + + public override Webhook Save(Webhook webhook) + { + string json = MifielUtils.ConvertObjectToJson(webhook); + HttpContent httpContent = new StringContent(json, Encoding.UTF8, "application/json"); + HttpContent httpResponse = ApiClient.Post(_webhooksPath, httpContent); + string response = httpResponse.ReadAsStringAsync().Result; + return MifielUtils.ConvertJsonToObject(response); + } + + /// + /// Trigger delivery for a webhook. + /// + /// Webhook id + /// UUID of the related resource included in the callback payload + /// When true, deliver immediately once instead of enqueueing retries + public string Trigger(string id, string resource, bool instant = false) + { + var body = new Dictionary + { + { "resource", resource }, + { "instant", instant } + }; + string json = MifielUtils.ConvertObjectToJson(body); + HttpContent httpContent = new StringContent(json, Encoding.UTF8, "application/json"); + HttpContent httpResponse = ApiClient.Post(_webhooksPath + "/" + id + "/trigger", httpContent); + return httpResponse.ReadAsStringAsync().Result; + } + } +} diff --git a/MifielAPI/MifielAPI/Objects/Webhook.cs b/MifielAPI/MifielAPI/Objects/Webhook.cs new file mode 100644 index 0000000..8e8506f --- /dev/null +++ b/MifielAPI/MifielAPI/Objects/Webhook.cs @@ -0,0 +1,23 @@ +using Newtonsoft.Json; + +namespace MifielAPI.Objects +{ + /// + /// Account-level webhook subscription. + /// See https://docs.mifiel.com/en/#tag/Webhooks + /// + public class Webhook + { + [JsonProperty("id")] + public string Id { get; set; } + + [JsonProperty("url")] + public string Url { get; set; } + + [JsonProperty("callback_type")] + public string CallbackType { get; set; } + + [JsonProperty("created_at")] + public string CreatedAt { get; set; } + } +} diff --git a/README.md b/README.md index 6e9fa82..d8a0ce6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,15 @@ # csharp-api-client -Mifiel API Client for C# -C# SDK for [Mifiel](https://www.mifiel.com) API. -Please read our [documentation](http://docs.mifiel.com/) for instructions on how to start using the API. +C# SDK for the [Mifiel](https://www.mifiel.com) API. + +## Documentation + +API reference, guides, and examples: + +- English: https://docs.mifiel.com/en/ +- Español: https://docs.mifiel.com/es/ + +This README covers installation and client setup only. ## Installation @@ -18,207 +25,38 @@ Or from the Visual Studio Package Manager Console: Install-Package MifielAPIClient ``` -## Usage - -For your convenience Mifiel offers a Sandbox environment where you can confidently test your code. +## Setup -To start using the API in the Sandbox environment you need to first create an account at [app-sandbox.mifiel.com](https://app-sandbox.mifiel.com). - -Once you have an account you will need an APP_ID and an APP_SECRET which you can generate in [app-sandbox.mifiel.com/settings/access-tokens](https://app-sandbox.mifiel.com/settings/access-tokens). - -Then you can configure the library with: +1. Create an account (production or [sandbox](https://app-sandbox.mifiel.com)). +2. Generate an `APP_ID` and `APP_SECRET` in [Access Tokens](https://app-sandbox.mifiel.com/settings/access-tokens). +3. Configure the client: ```csharp - using MifielAPI; +using MifielAPI; - ApiClient apiClient = new ApiClient(appId, appSecret); - // if you want to use our sandbox environment use: - apiClient.Url = "https://app-sandbox.mifiel.com"; +ApiClient apiClient = new ApiClient(appId, appSecret); +// Production is the default (https://app.mifiel.com). +// For sandbox: +apiClient.Url = "https://app-sandbox.mifiel.com"; ``` -By default the client talks to production (`https://app.mifiel.com`). - -Document methods: - -- Find: - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - - Documents documents = new Documents(apiClient); - Document document = documents.Find("id"); - document.OriginalHash; - document.File; - document.FileSigned; - // ... - ``` - -- Find all: - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - using System.Collections.Generic; - - Documents documents = new Documents(apiClient); - List allDocuments = documents.FindAll(); - ``` - -- Create: - -> Use only **original_hash** if you dont want us to have the file.
-> Only **file** or **original_hash** must be provided. - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - using MifielAPI.Utils; - using System.Collections.Generic; - - Documents documents = new Documents(_apiClient); - Document document = new Document() - { - File = "path/to/my-file.pdf", - Signatures = new List() - { - new Signature() - { - SignatureStr = "Signer 1", - Email = "signer1@email.com", - TaxId = "AAA010101AAA" - }, - new Signature() - { - SignatureStr = "Signer 2", - Email = "signer2@email.com", - TaxId = "AAA010102AAA" - } - } - }; - - documents.Save(document); - - // if you dont want us to have the PDF, you can just send us - // the original_hash and the name of the document. Both are required - Document document2 = new Document() - { - OriginalHash = MifielUtils.GetDocumentHash("path/to/my-file.pdf"), - Signatures = ... - } - - documents.Save(document2); - ``` - -- Save Document related files - -```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - using MifielAPI.Utils; - - Documents documents = new Documents(apiClient); - Document document = documents.Find("id"); - - //save the original file - documents.SaveFile(document.Id, "path/to/save/file.pdf"); - //save the signed xml file - documents.SaveXml(document.Id, "path/to/save/xml.xml"); - - //append pdf base64 in original xml (when document was created using the hash) - MifielUtils.AppendPDFBase64InOriginalXml("path/to/file.pdf", "path/to/originalXml", "path/to/newXml"); -``` - -- Delete - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - - Documents documents = new Documents(apiClient); - documents.Delete("id"); - ``` - -Certificate methods: - -- Find: - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - - Certificates certificates = new Certificates(apiClient); - Certificate certificate = certificates.Find("id"); - certificate.CerHex; - certificate.TypeOf; - // ... - ``` - -- Find all: - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - using System.Collections.Generic; - - Certificates certificates = new Certificates(apiClient); - List allCertificates = certificates.FindAll(); - ``` - -- Create - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - - Certificates certificates = new Certificates(apiClient); - Certificate certificate = new Certificate(); - certificate.File = "path/to/my-certificate.cer"; - - certificates.Save(certificate); - ``` - -- Delete - - ```csharp - using MifielAPI.Dao; - using MifielAPI.Objects; - - Certificates certificates = new Certificates(apiClient); - certificates.Delete("id"); - ``` - ## Releasing This SDK ships as the NuGet package **MifielAPIClient** ([nuget.org/packages/MifielAPIClient](https://www.nuget.org/packages/MifielAPIClient)). It targets `net8.0` and is built with the .NET SDK (`dotnet pack` / `dotnet nuget push`). -1. **Bump the version** in `MifielAPI/MifielAPI/MifielAPI.csproj` (``) and add a heading in `CHANGELOG.md`. The `User-Agent` package version is read from that assembly attribute; do not hard-code it elsewhere. +1. **Bump the version** in `MifielAPI/MifielAPI/MifielAPI.csproj` (``) and add a heading in `CHANGELOG.md`. 2. **Pack:** ```shell dotnet pack MifielAPI/MifielAPI/MifielAPI.csproj -c Release -o artifacts ``` - The artifact is `artifacts/MifielAPIClient..nupkg`. -3. **Publish to nuget.org** with an API key from [nuget.org/account/apikeys](https://www.nuget.org/account/apikeys). Versions cannot be overwritten once pushed. +3. **Publish to nuget.org** with an API key from [nuget.org/account/apikeys](https://www.nuget.org/account/apikeys): ```shell dotnet nuget push artifacts/MifielAPIClient..nupkg \ --source https://api.nuget.org/v3/index.json \ --api-key "$NUGET_API_KEY" ``` -4. **Tag the git commit** and create a GitHub release: - - ```shell - git tag v - git push origin v - gh release create v --title "v" --notes-file CHANGELOG.md - ``` -The listing usually appears on nuget.org within a few minutes. Confirm at `https://www.nuget.org/packages/MifielAPIClient/`. - -Smoke tests (optional) use the same SDK: - -```shell -dotnet test MifielAPI/MifielAPI.sln --filter Category=Smoke -``` +4. **Tag the git commit** and create a GitHub release.